/**
 * \file doxygen.c
 * \mainpage RTOS - Project 2
 *
 * \section requirements REQUIREMENTS
 *
 * This is a simple RTOS that supports pre-emptive multithreading, and
 * interprocess synchronization using Events.
 *
 * \subsection assumptions Global Assumptions 
 *
 *    (ATMEL specific)
 *  - Counter1 Timer and SWI interrupts are reserved.
 * 
 *  - All runtime exceptions (where assumptions are violated) or other  
 *    unrecoverable errors get handled by calling OS_Abort().  
 *  - Each valid entry in PPP[] must be non-zero except IDLE.
 *  - All unspecified runtime errors have undefined behaviours, e.g., stack overflow.
 *  - PPP[] \b cannot be modified once the application starts running.
 *
 * \subsection policy Scheduling Policy   
 *
 *   There are three scheduling levels: SYSTEM, PERIODIC and RR.
 *   These levels are prioritized with SYSTEM being the highest, and RR being
 *   the lowest.
 *
 *   Preemption occurs immediately. Whenever preemption is feasible, it takes
 *   place instantly. As soon as a higher priority task becomes ready, it
 *   preempts all lower priority tasks.
 *
 * \subsection system System Tasks
 *
 *   SYSTEM (level) tasks are FCFS; they run to completion, i.e., until they
 *   terminate, block or yield. Thus, they are non-preemptible, not even by
 *   other SYSTEM tasks. They should only be used for critical system level
 *   activities, e.g., error or fault recovery. Running too many SYSTEM tasks 
 *   could affect the real time performance  of all other low level tasks. 
 *
 *
 * \subsection periodic Periodic Tasks
 *
 *   PERIODIC tasks are scheduled based on a fixed cyclic scheduling plan;
 *   they are time-based. (See below about PPP[].) Since they are time-critical,
 *   they are \b NOT allowed to block (i.e., wait on an event).
 *   When a PERIODIC task is created, it is assigned a "name", 
 *   a non-zero user-defined constant between 1 and MAXPROCESS.
 *   This name is fixed and can NEVER be changed again. 
 *   No two PERIODIC tasks have the same name. All names are unique. 
 *   Since tasks may terminate and be created again over time, 
 *   the same name may be reused over time for different PERIODIC task
 *   instance.
 *
 *   The PPP[] array is essentially a linear representation of a Gantt diagram.
 *   It is an array of [Name1, Interval1, Name2, Interval 2, ... ].
 *   The name of every PERIODIC task must appear in PPP[] array at least once,
 *   but may be more than once.
 * 
 *   For example, if we create three PERIODIC tasks with names A, B and 
 *   C out of three functions P(), Q() and R() respectively. Then, 
 *   PPP[] = { A, 2, B, 3, A, 5, C, 1 } means executing A for 2 ticks,
 *   then B for 3 ticks, then A again for 5 ticks, then C for 1 tick,
 *   then A again, and so on. The total cycle time is 2+3+5+1=11 ticks.
 *   That is, within 11 ticks, A executes twice, B once and C once. 
 *   If P() terminates, but the name A is later assigned to another function U(), 
 *   then A will be executed again according to PPP[] order using U(). 
 *   In a sense, PPP[] specifies at least a single execution cycle 
 *   of all PERIODIC tasks. IDLE is a special PERIODIC task name, which means
 *   do nothing during this task's assigned interval.
 *
 *   A PERIODIC task may yield (calling Task_Next()) to relinquish
 *   the processor before its assigned interval. In this case, it has completed
 *   its current execution interval and is waiting for its next interval.
 * 
 *   It is a runtime error if a PERIODIC task executes longer than the
 *   currently assigned interval. It is important NOT to underestimate
 *   the execution time requirement of a PERIODIC task. Choosing the appropriate
 *   execution order and intervals for all PERIODIC tasks is the responsibility
 *   of the Application Design Engineer(s), not our RTOS. Hence, all timing
 *   violations should be caught and then reported.
 *
 *   By specifying PPP[] and scheduling our PERIODIC tasks accordingly,
 *   we shall know precisely the execution "cycle" time of all such tasks, 
 *   thus their best execution frequency/rate and response time. This is how
 *   we guarantee the predictability of timing and ordering all critical
 *   activities.
 *
 *  \subsection rr RR Tasks
 *   
 *   RR tasks are scheduled in a round-robin fashion, i.e., each RR
 *   task runs for one TICK approximately and yields to the next RR task. They
 *   don't have any time critical schedule to follow, thus they share the
 *   processor cycles fairly.
 *
 *   RR tasks are allowed to run \a only when no PERIODIC or SYSTEM tasks
 *   are executing. When an RR task resumes after pre-emption, 
 *   it re-enters its RR level at the end. When an RR task
 *   yields, or resumes after being unblocked, it re-enters its level
 *   at the end as well.
 *
 *
 *  \subsection boot OS Booting
 *     Our RTOS is compiled together with an application. It doesn't provide
 *     a "main()" function, which is a part of the application. By convention,
 *     the "main()" is the first function to be called by the C runtime code, 
 *     "crt0.S". For our RTOS, we shall change this convention as follows: 
 *     -# OS_Init() is called from crt0.S as the very first C function to be
 *        executed instead of main().
 *     -# Upon completion of OS_Init(), the application's main() is then
 *        created as the first and only SYSTEM level task.
 *     -# In main(), the rest of the application tasks are then created.
 *     -# In order for all other application tasks to run, our main() task
 *        must either terminate or block on an event. (For example, main()
 *        may become a "watchdog" task to reset the entire application.)
 *
 *
 * \subsection ipc Interprocess Communication
 *
 *    Events are one-way synchronization signals. They don't have any "memory"
 *    (i.e., values); thus, they are NOT semaphores. Any SYSTEM or RR task may
 *    wait on an event; PERIODIC tasks \b MUST \b NOT wait on any event.
 *    However, any task may signal/broadcast an event.
 *    A waiting task is resumed when the associated event is signalled.
 *    All waiting tasks are resumed when the associated event is broadcasted.
 *    When an event is signalled (or broadcasted) but there are no waiting tasks,
 *    this is a \a no-op; hence, events have \b no memory.
 *
 * \section design DESIGN IMPLEMENTATION
 * 
 * The first function in our real-time operating system that executes is OS_Init(). After initializing the clock prescaler, the kernel, and the queues, tasks are created. First the idle task is created, then the PPP array is read and \b task_executers are created for each periodic task, and finally the main task is created. The last thing OS_Init() does is calls Next_Kernel_Request(), which is the main loop of the kernel.
 * 
 * The following design architecture illustrates how the RTOS is logically organized and which interfaces available to the application.
 * \htmlonly <div align="center"><a href="components.jpg" target="_blank"><img src="components_t.jpg" border="0"></a></div> \endhtmlonly
 *
 * \subsection clock Clock Prescaler
 * 
 * The clock has been prescaled by 1024. This choice of prescaler is used because there is no need for faster or more precise interruptions.
 * 
 * \subsection queue Queues
 * 
 * The use of pointers alone to keep track of ready tasks became very repetitive. The pointers were encapsulated inside queues in order to obtain the most optimized end result. A queue is required for each type of task. The SYSTEM task queue is always checked for ready tasks first, then the PERIODIC task queue, and finally the RR task queue. If there are no tasks on any queue, the IDLE task is executed until another task becomes ready.
 * 
 * \subsection  ppparray Traversing the PPP array
 * 
 * When the PPP array is read, \b task_executers are created in order to attain constant time when cycling through the PPP[]. Further, reading the PPP[] in this manner protects the system in the event that the PPP array is changed later. If a task is being called that was not in the original PPP[], the RTOS simply considers the task to be IDLE.
 * 
 * \subsection taskarchitecture Task Architecture
 * 
 * A task consists of three parts: TASK_EXECUTER, TASK_DESCRIPTOR, and TASK_CONSTRUCTOR.
 * 
 * \b Task_executer is a handler responsible for controlling the execution time of a task respresented by a \b task_descriptor. It was created for the sole purpose of being able to read the PPP[] in constant time. It contains the name and time interval provided in the PPP[] as well as the owner, level, number of ticks, kernel type request, and a link to the \b task_descriptor. For PERIODIC tasks, the \c task pointer initially points to the IDLE task until the corresponding task is created.
 * 
 * \b Task_descriptor contains information that pertains to the individual task (ie. the stack pointer, the workspace, a link to the \b task_constructor, and the state of the task).
 * 
 * \b Task_constructor was created to store the information (ie. name, a pointer to the code, argument, and level) necessary to create a new task. It was a design structure to help understand the task creation process. During testing, it was verified that the contents of this structure could be merged with \b task_descriptor. However, due to a time deadline, this structure was kept as originally designed.
 * 
 * \section futureimplementations FUTURE IMPLEMENTATIONS
 * 
 * \li Simplify the task architecture and optimize the code by merging \b task_constructor with \b task_descriptor.
 * \li Adjust Timer to handle 'missed' interruptions (ie. when global interruptions is temporary disabled).
 * \li Implement a 'WaitForNext' function which handles the case when there is not time enough to switch context to the next RR task, so it should wait for the next PERIODIC task.
 * 
 */
